xtf-linkui

Appearance

android ios调用手机系统服务打印图片pdf 文档 ​

插件 ID: 22464
来源: https://ext.dcloud.net.cn/plugin?id=22464
Android、iOS 调用系统打印服务，实现手机本地打印图片和 PDF，支持常用打印参数

更新记录 ​

​

                                                    1.0.3（2026-06-01）

优化已知问题和增加ios 版本

​

                                                    1.0.2（2025-11-18）

优化

​

                                                    1.0.1（2025-03-26）

优化 查看更多

平台兼容性 ​

uni-app(4.13) ​

| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 | | | √ | √ |

  • |
  • |
  • | √ | 5.1 | √ |
  • | | | 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 | | |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • | |

uni-app x(4.11) ​

| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 | | |

  • |
  • | 5.1 | √ |
  • |
  • | |

xtf-printer ​

系统打印插件，支持在 uni-app / uni-app x 的 App 端调起系统打印能力，打印本地图片或本地 PDF。

功能说明 ​

  • 打印本地图片
  • 打印本地 PDF
  • 支持设置打印名称
  • 支持颜色模式
  • 支持纸张尺寸
  • 支持打印方向
  • 支持图片缩放模式
  • 支持自定义页边距

适用范围 ​

平台支持矩阵 ​

| 平台 | 状态 | 说明 | | | Android App (uni-app) | 支持 | 支持图片、PDF 打印，参数支持最完整 | | | Android App (uni-app x) | 支持 | 支持图片、PDF 打印，参数支持最完整 | | | iOS App (uni-app) | 支持 | 支持图片、PDF 打印，当前已支持 name、orientation | | | iOS App (uni-app x) | 支持 | 支持图片、PDF 打印，当前已支持 name、orientation | | | Harmony App | 暂不支持 | 当前版本未提供正式实现 | | | Web | 不支持 | 浏览器端不在本插件支持范围内 | | | 小程序平台 | 不支持 | 微信、支付宝、抖音等小程序均不支持 | |

支持平台 ​

  • uni-app Android App
  • uni-app x Android App
  • uni-app iOS App
  • uni-app x iOS App

不支持平台 ​

  • Web
  • 微信小程序等小程序平台
  • Harmony

使用前提 ​

  • 这是 App 原生打印能力插件，必须在 Android 或 iOS 真机环境下使用。
  • Android 端需要使用自定义基座测试，标准基座下原生依赖无法完整生效。
  • 设备本身需要支持系统打印服务，并已经配置可用打印机或 AirPrint 设备。
  • Android 原生编译时，HBuilderX 运行配置中需要正确配置 JDK 路径。

安装后检查 ​

  • 确认插件已安装到 uni_modules/xtf-printer
  • 确认 Android 端运行到自定义基座
  • 确认待打印文件真实存在
  • 确认图片或 PDF 路径可被当前 App 读取

引入方式 ​

import { xtf, PrintPara } from "@/uni_modules/xtf-printer"

API ​

xtf.isPrinterEnable() ​

检测当前设备是否可以获取系统打印服务。

const enabled = xtf.isPrinterEnable()
console.log("printer enabled:", enabled)

xtf.printerImage(para) ​

打印图片。

xtf.printerPdf(para) ​

打印 PDF。

iOS 参数说明 ​

iOS 端当前优先保证图片和 PDF 的系统打印能力可用，name 会作为打印任务名生效。 以下参数在 iOS 端当前已支持或部分支持：

  • name
  • orientation 以下参数在 Android 端有实现，但 iOS 端暂未逐项映射到系统打印面板：
  • colorMode
  • mediaSize
  • margins
  • scalType

PrintPara 参数说明 ​

export type PrintPara = {
  name?: string
  path: string
  colorMode?: number
  mediaSize?: number
  margins?: number[]
  scalType?: number
  orientation?: number
}

参数说明：

  • name：打印任务名称，可选，默认值为 print
  • path：待打印文件路径，必填
  • colorMode：颜色模式，0 为黑白，1 为彩色
  • mediaSize：纸张大小，默认 4，即 A4
  • margins：页边距数组，长度必须为 4
  • scalType：图片缩放模式，0 为适应，1 为填充
  • orientation：打印方向，0 为竖向，1 为横向

mediaSize 对照 ​

  • 0：A0
  • 1：A1
  • 2：A2
  • 3：A3
  • 4：A4
  • 5：A5
  • 6：A6
  • 7：A7
  • 8：A8
  • 9：A9
  • 10：A10
  • 11：B0
  • 12：B1
  • 13：B2
  • 14：B3
  • 15 及之后的部分 B 系列值：当前实现仍按插件内部映射处理

路径说明 ​

打印项目内静态资源 ​

支持直接传入 /static/ 开头的路径，例如：

path: "/static/logo.png"
path: "/static/a.pdf"

打印本地绝对路径文件 ​

如果文件不是项目静态资源，也可以传入 Android 可访问的本地绝对路径。

uni-app x 示例 ​

import { xtf, PrintPara } from "@/uni_modules/xtf-printer"
xtf.printerImage({
  name: "image-demo",
  path: "/static/logo.png",
  colorMode: 1,
  orientation: 0,
  scalType: 0
} as PrintPara)
xtf.printerPdf({
  name: "pdf-demo",
  path: "/static/a.pdf",
  colorMode: 1,
  mediaSize: 4,
  orientation: 0
} as PrintPara)

uni-app 示例 ​

import { xtf } from "@/uni_modules/xtf-printer"
xtf.printerImage({
  name: "image-demo",
  path: "/static/logo.png",
  colorMode: 1,
  orientation: 0,
  scalType: 0
})
xtf.printerPdf({
  name: "pdf-demo",
  path: "/static/a.pdf",
  colorMode: 1,
  mediaSize: 4,
  orientation: 0
})

页面按钮示例 ​

<template>
  <view>
    <button @click="printImage">打印图片</button>
    <button @click="printPdf">打印 PDF</button>
  </view>
</template>
<script>
import { xtf, PrintPara } from "@/uni_modules/xtf-printer"
export default {
  methods: {
    printImage() {
      xtf.printerImage({
        name: "test-image",
        path: "/static/logo.png"
      } as PrintPara)
    },
    printPdf() {
      xtf.printerPdf({
        name: "test-pdf",
        path: "/static/a.pdf"
      } as PrintPara)
    }
  }
}
</script>

常见问题 ​

1. 出现 Can print only from an activity ​

这是 Android 系统打印要求必须从页面 Activity 发起。请使用插件最新版本，并在页面点击事件中调用打印方法，不要在应用未完成页面绑定时提前调用。

2. 为什么标准基座下无法正常打印 ​

因为 Android 端依赖原生能力和三方依赖，标准基座下不能完整生效。请改用自定义基座。

3. 为什么编译时提示需要配置 JDK ​

因为 Android 原生插件编译依赖本地 JDK。请在 HBuilderX 的运行配置中填写正确的 JDK 根目录，注意不要填写到 bin 目录。iOS 端不依赖这个配置。

4. 为什么点了打印没有反应 ​

请依次检查：

  • 是否使用 Android 真机
  • Android 端是否使用自定义基座
  • 是否已配置系统打印服务
  • 文件路径是否正确
  • 文件是否真实存在

注意事项 ​

  • 推荐在用户点击按钮后再调用打印。
  • PDF 打印请确保传入的是本地可读文件路径。
  • 图片打印请确保图片文件可正常解码。
  • iOS 端当前已支持 name、orientation，其余部分 Android 参数暂不保证完全对齐。
  • 如果是插件市场购买版，使用前请先在自己的设备和业务场景中完整测试。

更新说明 ​

  • 1.0.2：新增 iOS 图片与 PDF 打印支持，并完善文档说明

开发参考 ​

MIT Licensed

Copyright © 2026 xtf-linkui